import SEO from '../components/SEO'

<SEO
  title="Breadcrumb"
  description="Breadcrumbs, or breadcrumb navigation, can help to enhance how users navigate to previous page levels of a website, especially if that website has many pages or products."
/>


# Breadcrumb

Breadcrumbs, or breadcrumb navigation, can help to enhance how users navigate
to previous page levels of a website, especially if that website has many pages
or products.

<br />

See `CBreadcrumb`'s [accessibility report](https://github.com/chakra-ui/chakra-ui-vue/blob/master/packages/chakra-ui-core/src/CBreadcrumb/accessibility.md)

<carbon-ad />

## Import 
Chakra UI exports four Breadcrumb related components:

- `CBreadcrumb`: The parent container for breadcrumbs.
- `CBreadcrumbItem`: Individual breadcrumb element containing a link and a divider.
- `CBreadcrumbLink`: The breadcrumb link.
- `CBreadcrumbSeparator`: The visual separator between each breadcrumb

<br />

```js
import {
  CBreadcrumb,
  CBreadcrumbItem,
  CBreadcrumbLink,
  CBreadcrumbSeparator,
} from "@chakra-ui/vue";
```

## Usage

Add `isCurrentPage` prop to the `CBreadcrumbItem` that matches the current path.
When this prop is present, the `CBreadcrumbItem` doesn't have a separator, and
the `CBreadcrumbLink` has `aria-current` set to `page`.

```vue live=true
<c-breadcrumb>
  <c-breadcrumb-item>
    <c-breadcrumb-link href="#">Breadcrumb 1</c-breadcrumb-link>
  </c-breadcrumb-item>

  <c-breadcrumb-item>
    <c-breadcrumb-link href="#">Breadcrumb 2</c-breadcrumb-link>
  </c-breadcrumb-item>

  <c-breadcrumb-item isCurrentPage>
    <c-breadcrumb-link href="#">Breadcrumb 2</c-breadcrumb-link>
  </c-breadcrumb-item>
</c-breadcrumb>
```

### Separators

Change the separator used in the `CBreadrumb` by passing a string, like `›`.

```vue live=true
<c-breadcrumb separator="›">
  <c-breadcrumb-item>
    <c-breadcrumb-link href="#">Breadcrumb 1</c-breadcrumb-link>
  </c-breadcrumb-item>

  <c-breadcrumb-item>
    <c-breadcrumb-link href="#">Breadcrumb 2</c-breadcrumb-link>
  </c-breadcrumb-item>

  <c-breadcrumb-item isCurrentPage>
    <c-breadcrumb-link href="#">Breadcrumb 2</c-breadcrumb-link>
  </c-breadcrumb-item>
</c-breadcrumb>
```

### Styling the Separator

To gain control over the style of the breadcrumb separator. Set `add-separator` prop
on the `CBreadcrumb` to `false`, and manually add the `CBreadcrumbSeparator` as a child of the
`CBreadcrumbItem`.

You can then pass style props to change the styling of the `CBreadcrumbSeparator`. You can also override
the content of the `CBreadcrumbSeparator` by passing its default slot.

```vue live=true
<c-breadcrumb :add-separator="false">
  <c-breadcrumb-item>
    <c-breadcrumb-link href="#">Breadcrumb 1</c-breadcrumb-link>
    <c-breadcrumb-separator color="tomato" font-size="10px" font-weight="bold" />
  </c-breadcrumb-item>

  <c-breadcrumb-item>
    <c-breadcrumb-link href="#">Breadcrumb 2</c-breadcrumb-link>
    <c-breadcrumb-separator color="firebrick" font-size="20px" />
  </c-breadcrumb-item>
  
  <c-breadcrumb-item isCurrentPage>
    <c-breadcrumb-link href="#">Breadcrumb 2</c-breadcrumb-link>
  </c-breadcrumb-item>
</c-breadcrumb>
```

## Composition

`CBreadcrumb` composes [CBox](/box) so you can pass all `CBox` props to change the
style of the breadcrumbs. Let's say we need to increase the `font-size` of the
breadcrumbs.

```vue live=true
<c-breadcrumb font-weight="medium" font-size="sm">
  <c-breadcrumb-item>
    <c-breadcrumb-link href="/google">Home</c-breadcrumb-link>
  </c-breadcrumb-item>

  <c-breadcrumb-item>
    <c-breadcrumb-link href="/about">About</c-breadcrumb-link>
  </c-breadcrumb-item>
  
  <c-breadcrumb-item isCurrentPage>
    <c-breadcrumb-link href="/current">Current</c-breadcrumb-link>
  </c-breadcrumb-item>
</c-breadcrumb>
```

## Usage with `router-link` or `nuxt-link`.

To use the `CBreadcrumb` with a routing Library like [Vue Router](https://router.vuejs.org),
all you need to do is to pass the `as` prop to the `CBreadcrumbLink` component.

It will replace the rendered `a` tag with `router-link` or `nuxt-link`.

```vue live=true
<c-breadcrumb separator="›">
  <c-breadcrumb-item>
    <c-breadcrumb-link as="nuxt-link" to="/">Components</c-breadcrumb-link>
  </c-breadcrumb-item>

  <c-breadcrumb-item>
    <c-breadcrumb-link as="nuxt-link" to="/breadcrumb">Breadcrumb</c-breadcrumb-link>
  </c-breadcrumb-item>
</c-breadcrumb>
```

## Accessibility

- The Breadcrumbs are rendered in a `nav` to denote that it's a navigation
  landmark.
- The `CBreadcrumb` `nav` has `aria-label` set to `breadcrumb`.
- The `CBreadcrumbItem` with `isCurrentPage` prop adds the `aria-current=page` to
  the `CBreadcrumbLink`.
- The separator has `role` set to `presentation` to denote that it's for
  presentation purposes.


## Props

### `CBreadcrumb` Props

| Name         | Type                        | Default  | Description                                                     |
| ------------ | --------------------------- | -------- | --------------------------------------------------------------- |
| separator    | `string`                    | `/`      | The visual separator between the breadcrumb item.               |
| spacing      | `StyledSystem.MarginProps`  | `0.5rem` | The left and right margin applied to the separator.             |
| addSeparator | `boolean`                   | `true`   | If `true`, the breadcrumb will add the separator automatically. |

### `CBreadcrumbItem` Props

| Name          | Type      | Default | Description                                                                                                    |
| ------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| isCurrentPage | `boolean` | false   | If `true`, it indicates that the breadcrumb link is active page, adds `aria-current=page` and renders a `span` |

<br />

### `CBreadcrumbLink` Props

The `CBreadcrumbLink` composes the <nuxt-link to="/link">CLink</nuxt-link> component so it accepts all CLink props.

<br />

### BreadcrumbSeparator Props

The BreadcrumbSeparator composes the <nuxt-link to="/box">CBox</nuxt-link> component so it accepts all CBox props.
